/*
 * StrategyGenerator.java
 *
 * Created on 21 de Fevereiro de 2008, 22:30
 *
 * To change this template, choose Tools | Template Manager
 * and open the template in the editor.
 */

package intopo.game;

/**
 * An interface that provides methods to create a certain number of
 * player's strategies. Implementators of this interface may provide
 * generators that provide player's strategies following the parameters
 * stored in some data file. Other implementors may provide unlimited
 * generators. An example of this are random generators.
 *
 * <p> This interface is used to initialise a population of players. In
 * this class implementators must provide finite generators.
 *
 * @param <S> The type of strategy that is used to play a game.

 * @author <a href="mailto:plsm@ua.pt">Pedro Lopes da Silva Mariano</a>

 * @version 1.0
 */
public interface StrategyGenerator<S extends Strategy<S>>
{
	/**
	 * How many strategies this generator can create.
	 *
	 * <p> A negative number makes the caller throw an {@code AssertionError} exception.
	 *
	 * <p> A return value of {@code Integer.MAX_VALUE} is interpreted as
	 * infinite. If the caller requires a finite number then it throws an
	 * {@code AssertionError} exception.
	 */
	public int numberStrategies ();

	/**
	 * Returns the next player's strategy.
	 *
	 * <p> Throws {@code IllegalStateException} if the generator has created
	 * all player's strategies that is capable of.
	 *
	 * @return A player's strategy.
	 *
	 * @throws IllegalStateException If this generator has exceed its
	 * creation capability.
	 */
	public S next ()
		throws IllegalStateException;
}
